home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / man.3 / 3DBorder.3 next >
Text File  |  1995-07-21  |  14KB  |  400 lines
  1. '\"
  2. '\" Copyright (c) 1990-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/wish/man/RCS/3DBorder.3,v 1.12 93/04/01 09:40:48 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS Tk_Get3DBorder tkc
  206. .BS
  207. .SH NAME
  208. Tk_Get3DBorder, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_Free3DBorder \- draw borders with three-dimensional appearance
  209. .SH SYNOPSIS
  210. .nf
  211. \fB#include <tk.h>\fR
  212. .sp
  213. Tk_3DBorder
  214. \fBTk_Get3DBorder(\fIinterp, tkwin, colorMap, colorName\fB)\fR
  215. .sp
  216. void
  217. \fBTk_Draw3DRectangle(\fIdisplay, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
  218. .sp
  219. void
  220. \fBTk_Fill3DRectangle(\fIdisplay, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
  221. .sp
  222. void
  223. \fBTk_Draw3DPolygon(\fIdisplay, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR
  224. .sp
  225. void
  226. \fBTk_Fill3DPolygon(\fIdisplay, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR
  227. .sp
  228. void
  229. \fBTk_SetBackgroundFromBorder(\fItkwin, border\fB)\fR
  230. .sp
  231. char *
  232. \fBTk_NameOf3DBorder(\fIborder\fB)\fR
  233. .sp
  234. .VS
  235. XColor *
  236. \fBTk_3DBorderColor(\fIborder\fB)\fR
  237. .VE
  238. .sp
  239. \fBTk_Free3DBorder(\fIborder\fB)\fR
  240. .SH ARGUMENTS
  241. .AS "Tk_3DBorder" borderWidth
  242. .AP Tcl_Interp *interp in
  243. Interpreter to use for error reporting.
  244. .AP Tk_Window tkwin in
  245. Token for window in which border will be drawn.
  246. .AP Colormap colormap in
  247. Colormap from which to allocate colors.  If None, then the default
  248. colormap for \fItkwin\fR's screen is used.
  249. .AP Tk_Uid colorName in
  250. Textual description of color corresponding to background (flat areas).
  251. Illuminated edges will be brighter than this, and shadowed edges will
  252. be darker than this.
  253. .AP Display *display in
  254. Xlib pointer indicating display with which drawable is associated.
  255. .AP Drawable drawable in
  256. X token for window or pixmap;  indicates where border is to be drawn.
  257. .AP Tk_3DBorder border in
  258. Token for border previously allocated in call to \fBTk_Get3DBorder\fR.
  259. .AP int x in
  260. X-coordinate of upper-left corner of rectangle describing border.
  261. .AP int y in
  262. Y-coordinate of upper-left corner of rectangle describing border.
  263. .AP int width in
  264. Width of rectangle describing border, in pixels.
  265. .AP int height in
  266. Height of rectangle describing border, in pixels.
  267. .AP int borderWidth in
  268. Width of border in pixels. Positive means border is inside rectangle
  269. given by \fIx\fR, \fIy\fR, \fIwidth\fR, \fIheight\fR, negative means
  270. border is outside rectangle.
  271. .AP int relief in
  272. Indicates 3-D position of interior of rectangle relative to exterior;
  273. should be TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, TK_RELIEF_GROOVE,
  274. .VS
  275. or TK_RELIEF_RIDGE (may also be TK_RELIEF_FLAT
  276. .VE
  277. for \fBTk_Fill3DRectangle\fR).
  278. .AP XPoint *pointPtr in
  279. Pointer to array of points describing the set of vertices in a polygon.
  280. The polygon need not be closed (it will be closed automatically if it
  281. isn't).
  282. .AP int numPoints in
  283. Number of points at \fI*pointPtr\fR.
  284. .AP int polyBorderWidth in
  285. Width of border in pixels.  If positive, border is drawn to left of
  286. trajectory given by \fIpointPtr\fR;  if negative, border is drawn to
  287. right of trajectory.  If \fIleftRelief\fR is TK_RELIEF_GROOVE or
  288. TK_RELIEF_RIDGE then the border is centered on the trajectory.
  289. .AP int leftRelief in
  290. Height of left side of polygon's path relative to right.  TK_RELIEF_RAISED
  291. means left side should appear higher and TK_RELIEF_SUNKEN means right side
  292. should appear higher;
  293. .VS
  294. TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean the obvious things.
  295. .VE
  296. For \fBTk_Fill3DPolygon\fR, TK_RELIEF_FLAT may also be specified to
  297. indicate no difference in height.
  298. .BE
  299.  
  300. .SH DESCRIPTION
  301. .PP
  302. These procedures provide facilities for drawing window borders in a
  303. way that produces a three-dimensional appearance.  \fBTk_Get3DBorder\fR
  304. allocates colors and Pixmaps needed to draw a border in the window
  305. given by the \fItkwin\fR argument.  The \fIcolormap\fR argument
  306. specifies a Colormap to use for allocating colors, and the \fIcolorName\fR
  307. argument indicates what colors should be used in the border.  \fIColorName\fR
  308. may be any value acceptable to \fBTk_GetColor\fR.  The color indicated
  309. by \fIcolorName\fR will not actually be used in the border;  it indicates
  310. the background color for the window (i.e. a color for flat surfaces).
  311. The illuminated portions of the border will appear brighter than indicated
  312. by \fIcolorName\fR, and the shadowed portions of the border will appear
  313. darker than \fIcolorName\fR.
  314. .PP
  315. \fBTk_Get3DBorder\fR returns a token that may be used in later calls
  316. to \fBTk_Draw3DRectangle\fR.  If an error occurs in allocating information
  317. for the border (e.g. \fIcolorName\fR isn't a legal color specifier),
  318. then NULL is returned and an error message is left in \fIinterp->result\fR.
  319. .PP
  320. Once a border structure has been created, \fBTk_Draw3DRectangle\fR may be
  321. invoked to draw the border.  The \fIdisplay\fR and \fIdrawable\fR
  322. arguments specify a window or pixmap in which the border is to be
  323. drawn.  \fIDrawable\fR need not refer to the same window as the
  324. \fItkwin\fR used to create the border, but it must refer to a compatible
  325. pixmap or window:  one associated with the same display and with the
  326. same depth as the \fItkwin\fR used to create the border.
  327. The \fIx\fR, \fIy\fR, \fIwidth\fR, and
  328. \fIheight\fR arguments define the bounding box of the border region
  329. within \fIdrawable\fR (usually \fIx\fR and \fIy\fR are zero and
  330. \fIwidth\fR and \fIheight\fR are the dimensions of the window), and
  331. \fIborderWidth\fR specifies the number of pixels actually
  332. occupied by the border.  The \fIrelief\fR argument indicates
  333. which of several three-dimensional effects is desired:
  334. TK_RELIEF_RAISED means that the interior of the rectangle should appear raised
  335. relative to the exterior of the rectangle, and
  336. TK_RELIEF_SUNKEN means that the interior should appear depressed.
  337. .VS
  338. TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean that there should appear to be
  339. a groove or ridge around the exterior of the rectangle.
  340. .VE
  341. .PP
  342. \fBTk_Fill3DRectangle\fR is somewhat like \fBTk_Draw3DRectangle\fR except
  343. that it first fills the rectangular area with the background color
  344. (one corresponding
  345. to the \fIcolorName\fR used to create \fIborder\fR).  Then it calls
  346. \fBTk_Draw3DRectangle\fR to draw a border just inside the outer edge of
  347. the rectangular area.  The argument \fIrelief\fR indicates the desired
  348. effect (TK_RELIEF_FLAT means no border should be drawn; all that
  349. happens is to fill the rectangle with the background color).
  350. .PP
  351. The procedure \fBTk_Draw3DPolygon\fR may be used to draw more complex
  352. shapes with a three-dimensional appearance.  The \fIpointPtr\fR and
  353. \fInumPoints\fR arguments define a trajectory, \fIpolyBorderWidth\fR
  354. indicates how wide the border should be (and on which side of the
  355. trajectory to draw it), and \fIleftRelief\fR indicates which side
  356. of the trajectory should appear raised.  \fBTk_Draw3DPolygon\fR
  357. draws a border around the given trajectory using the colors from
  358. \fIborder\fR to produce a three-dimensional appearance.  If the trajectory is
  359. non-self-intersecting, the appearance will be a raised or sunken
  360. polygon shape.  The trajectory may be self-intersecting, although
  361. it's not clear how useful this is.
  362. .PP
  363. \fBTk_Fill3DPolygon\fR is to \fBTk_Draw3DPolygon\fR what
  364. \fBTk_Fill3DRectangle\fR is to \fBTk_Draw3DRectangle\fR:  it fills
  365. the polygonal area with the background color from \fIborder\fR,
  366. then calls \fBTk_Draw3DPolygon\fR to draw a border around the
  367. area (unless \fIleftRelief\fR is TK_RELIEF_FLAT;  in this case no
  368. border is drawn).
  369. .PP
  370. The procedure \fBTk_SetBackgroundFromBorder\fR will modify the background
  371. pixel and/or pixmap of \fItkwin\fR to produce a result compatible
  372. with \fIborder\fR.  For color displays, the resulting background will
  373. just be the color given by the \fIcolorName\fR argument passed to
  374. \fBTk_Get3DBorder\fR when \fIborder\fR was created;  for monochrome
  375. displays, the resulting background
  376. will be a light stipple pattern, in order to distinguish the background from
  377. the illuminated portion of the border.
  378. .PP
  379. Given a token for a border, the procedure \fBTk_NameOf3DBorder\fR
  380. will return the \fIcolorName\fR string that was passed to
  381. \fBTk_Get3DBorder\fR to create the border.
  382. .PP
  383. .VS
  384. The procedure \fBTk_3DBorderColor\fR returns the XColor structure
  385. that will be used for flat surfaces drawn for its \fIborder\fR
  386. argument by procedures like \fBTk_Fill3DRectangle\fR.
  387. The return value corresponds to the \fIcolorName\fR passed to
  388. \fBTk_Get3DBorder\fR.
  389. The XColor, and its associated pixel value, will remain allocated
  390. as long as \fIborder\fR exists.
  391. .VE
  392. .PP
  393. When a border is no longer needed, \fBTk_Free3DBorder\fR should
  394. be called to release the resources associated with the border.
  395. There should be exactly one call to \fBTk_Free3DBorder\fR for
  396. each call to \fBTk_Get3DBorder\fR.
  397.  
  398. .SH KEYWORDS
  399. 3D, background, border, color, depressed, illumination, polygon, raised, shadow, three-dimensional effect
  400.